home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kssl.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  8.0 KB  |  302 lines
  1. /* This file is part of the KDE project
  2.  *
  3.  * Copyright (C) 2000-2003 George Staikos <staikos@kde.org>
  4.  *
  5.  * This library is free software; you can redistribute it and/or
  6.  * modify it under the terms of the GNU Library General Public
  7.  * License as published by the Free Software Foundation; either
  8.  * version 2 of the License, or (at your option) any later version.
  9.  *
  10.  * This library is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  * Library General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Library General Public License
  16.  * along with this library; see the file COPYING.LIB.  If not, write to
  17.  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  * Boston, MA 02110-1301, USA.
  19.  */
  20.  
  21. #ifndef _KSSL_H
  22. #define _KSSL_H
  23.  
  24. #include <ksslsettings.h>
  25. #include <ksslpeerinfo.h>
  26. #include <ksslconnectioninfo.h>
  27.  
  28. class KSSLPrivate;
  29. class KSSLCertificate;
  30. class KSSLPKCS12;
  31. class KSSLSession;
  32.  
  33. /**
  34.  * KDE SSL Wrapper Class
  35.  *
  36.  * This class implements KDE's SSL support by wrapping OpenSSL.
  37.  *
  38.  * @author George Staikos <staikos@kde.org>
  39.  * @see KExtendedSocket, TCPSlaveBase
  40.  * @short KDE SSL Class
  41.  */
  42. class KIO_EXPORT KSSL {
  43. public:
  44.     /**
  45.      *  Construct a KSSL object
  46.      *
  47.      *  @param init Set this to false if you do not want this class to
  48.      *         immediately initialize OpenSSL.
  49.      */
  50.     KSSL(bool init = true);
  51.  
  52.     /**
  53.      *  Destroy this KSSL object
  54.      *
  55.      *  Does not close any socket.
  56.      */
  57.     ~KSSL();
  58.  
  59.     /**
  60.      *  Determine if SSL is available and works.
  61.      *
  62.      *  @return true is SSL is available and usable
  63.      */
  64.     static bool doesSSLWork();
  65.  
  66.     /**
  67.      *  Initialize OpenSSL.
  68.      *
  69.      *  @return true on success
  70.      *
  71.      *  This will do nothing if it is already initialized.
  72.      *  @see reInitialize
  73.      */
  74.     bool initialize();
  75.  
  76.     /**
  77.      *  This is used for applicationss which do STARTTLS or something
  78.      *  similar. It creates a TLS method regardless of the user's settings.
  79.      *
  80.      *  @return true if TLS is successfully initialized
  81.      */
  82.     bool TLSInit();
  83.  
  84.     /**
  85.      *  Set an SSL session to use.  This deep copies the session so it
  86.      *  doesn't have to remain valid.  You need to call it after calling
  87.      *  initialize or reInitialize.  The ID is cleared in close().
  88.      *
  89.      *  @param session A valid session to reuse.  If 0L, it will clear the
  90.      *                 session ID in memory.
  91.      *
  92.      *  @return true on success
  93.      */
  94.     bool setSession(const KSSLSession *session);
  95.  
  96.     /**
  97.      *  Close the SSL session.
  98.      */
  99.     void close();
  100.  
  101.     /**
  102.      *  Reinitialize OpenSSL.
  103.      *
  104.      *  @return true on success
  105.      *
  106.      *  This is not generally needed unless you are reusing the KSSL object
  107.      *  for a new session.
  108.      *  @see initialize
  109.      */
  110.     bool reInitialize();
  111.  
  112.     /**
  113.      *  Trigger a reread of KSSL configuration and reInitialize() KSSL.
  114.      *
  115.      *  @return true on successful reinitalizations
  116.      *
  117.      *  If you setAutoReconfig() to false, then this will simply
  118.      * reInitialize() and not read in the new configuration.
  119.      *  @see setAutoReconfig
  120.      */
  121.     bool reconfig();
  122.  
  123.     /**
  124.      *  Enable or disable automatic reconfiguration on initialize().
  125.      *
  126.      *  @param ar Set to false in order to disable auto-reloading of the
  127.      *         KSSL configuration during initialize().
  128.      *
  129.      *  By default, KSSL will read its configuration on initialize().  You
  130.      *  might want to disable this for performance reasons.
  131.      */
  132.     void setAutoReconfig(bool ar);
  133.  
  134.     /**
  135.      *  This will reseed the pseudo-random number generator with the EGD
  136.      *  (entropy gathering daemon) if the EGD is configured and enabled.
  137.      *  You don't need to call this yourself normally.
  138.      *
  139.      *  @return 0 on success
  140.      */
  141.     int seedWithEGD();
  142.  
  143.     /**
  144.      *  Set a new KSSLSettings instance as the settings. This deletes the
  145.      *  current instance of KSSLSettings.
  146.      *
  147.      *  @param settings A new, valid settings object.
  148.      *
  149.      *  @return true on success
  150.      */
  151.     bool setSettings(KSSLSettings *settings);
  152.  
  153.     /**
  154.      *  One is built by the constructor, so this will only return a NULL
  155.      *  pointer if you set one with setSettings().
  156.      *
  157.      *  @return the current settings instance
  158.      */
  159.     KSSLSettings * settings() { return m_cfg; }
  160.  
  161.     /**
  162.      *  Use this to set the certificate to send to the server.
  163.      *  Do NOT delete the KSSLPKCS12 object until you are done with the
  164.      *  session. It is not defined when KSSL will be done with this.
  165.      *
  166.      *  @param pkcs the valid PKCS#12 object to send.
  167.      *
  168.      *  @return true if the certificate was properly set to the session.
  169.      */
  170.     bool setClientCertificate(KSSLPKCS12 *pkcs);
  171.  
  172.     /**
  173.      *  Set the status of the connection with respect to proxies.
  174.      *
  175.      *  @param active is not used
  176.      *  @param realIP is the IP address of the host you're connecting to
  177.      *  @param realPort is the port of the host you're connecting to
  178.      *  @param proxy is the IP or hostname of the proxy server
  179.      *  @deprecated
  180.      */
  181.     void setProxyUse(bool active, QString realIP = QString::null, int realPort = 0, QString proxy = QString::null) KDE_DEPRECATED;
  182.  
  183.     /**
  184.      *  Set the peer hostname to be used for certificate verification.
  185.      *
  186.      *  @param realHost the remote hostname as the user believes to be
  187.      *         connecting to
  188.      */
  189.     void setPeerHost(QString realHost = QString::null);
  190.  
  191.     /**
  192.      *  Connect the SSL session to the remote host using the provided
  193.      *  socket descriptor.
  194.      *
  195.      *  @param sock the socket descriptor to connect with.  This must be
  196.      *         an already connected socket.
  197.      *  @return 1 on success, 0 on error setting the file descriptor,
  198.      *          -1 on other error.
  199.      */
  200.     int connect(int sock);
  201.  
  202.     /**
  203.      *  Connect the SSL session to the remote host using the provided
  204.      *  socket descriptor.  This is for use with an SSL server application.
  205.      *
  206.      *  @param sock the socket descriptor to connect with.  This must be
  207.      *         an already connected socket.
  208.      *  @return 1 on success, 0 on error setting the file descriptor,
  209.      *          -1 on other error.
  210.      */
  211.     int accept(int sock);
  212.  
  213.     /**
  214.      *  Read data from the remote host via SSL.
  215.      *
  216.      *  @param buf the buffer to read the data into.
  217.      *  @param len the maximum length of data to read.
  218.      *  @return the number of bytes read, 0 on an exception, or -1 on error.
  219.      */
  220.     int read(void *buf, int len);
  221.  
  222.     /**
  223.      *  Peek at available data from the remote host via SSL.
  224.      *
  225.      *  @param buf the buffer to read the data into.
  226.      *  @param len the maximum length of data to read.
  227.      *  @return the number of bytes read, 0 on an exception, or -1 on error.
  228.      */
  229.     int peek(void *buf, int len);
  230.  
  231.     /**
  232.      *  Write data to the remote host via SSL.
  233.      *
  234.      *  @param buf the buffer to read the data from.
  235.      *  @param len the length of data to send from the buffer.
  236.      *  @return the number of bytes written, 0 on an exception,
  237.      *          or -1 on error.
  238.      */
  239.     int write(const void *buf, int len);
  240.  
  241.     /**
  242.      *  Determine if data is waiting to be read.
  243.      *
  244.      *  @return -1 on error, 0 if no data is waiting, > 0 if data is waiting.
  245.      */
  246.     int pending();
  247.  
  248.     /**
  249.      *  Obtain a reference to the connection information.
  250.      *
  251.      *  @return a reference to the connection information,
  252.      *          valid after connected
  253.      *  @see KSSLConnectionInfo
  254.      */
  255.     KSSLConnectionInfo& connectionInfo();
  256.  
  257.     /**
  258.      *  Obtain a reference to the information about the peer.
  259.      *
  260.      *  @return a reference to the peer information,
  261.      *          valid after connected
  262.      *  @see KSSLPeerInfo
  263.      */
  264.     KSSLPeerInfo& peerInfo();
  265.  
  266.     /**
  267.      *  Obtain a pointer to the session information.
  268.      *
  269.      *  @return a pointer to the session information.
  270.      *          This is valid after connected, while connected.
  271.      *          It is deleted by the KSSL object which returns it.
  272.      *          May return 0L if no valid session exists.
  273.      *  @see KSSLSession
  274.      */
  275.     const KSSLSession* session() const;
  276.  
  277.     /**
  278.      *  Determine if we are currently reusing an SSL session ID.
  279.      *
  280.      *  @return true if we are reusing a session ID.
  281.      */
  282.     bool reusingSession() const;
  283.  
  284. private:
  285.     static bool m_bSSLWorks;
  286.     bool m_bInit;
  287.     bool m_bAutoReconfig;
  288.     KSSLSettings *m_cfg;
  289.     KSSLConnectionInfo m_ci;
  290.     KSSLPeerInfo m_pi;
  291.  
  292.     KSSLPrivate *d;
  293.  
  294.     void setConnectionInfo();
  295.     void setPeerInfo();
  296.     bool setVerificationLogic();
  297. };
  298.  
  299.  
  300. #endif
  301.  
  302.